Standard Docs¶

We have borrowed concepts from this and this articles in order to encourage a culture of written communication. This way, we will be able to:

• Assign proper time to think and propose ideas.
• Be able to get feedback from peers about different implementation ideas.
• Deliver a spec that should be easily translated to tasks therefore code without any ambiguities.
• Share ideas and reduce the bus factor.
• Be accountable for our decisions.

Project engineering docs¶

There are some strandard documents that need to be created in order to propose, discuss, ask for peer reviews and document different technical decisions made during a project or in the engineering team.

Atix - Technical Specs¶

• During the first days just after the project started, the solution technical specs and architecture document must be written.
• It's main goal is to explain how the solution is going to be built.
• It should work as:
  • A guide for the team members to understand the project technical approach.
  • A tool to document each decision made and, most importantly, to express the ones that didn't make it and the rationale behind it.
  • A document to be reviewed by the stakeholders (customer) to verify they are comfortable with the solution they are going to receive.
• It's Technical Leader (TL) responsibility to write it and keep it updated (obviously writing can be delegated).
• Every section should be written based on the guidelines written on the template. Sections that don't apply shouldn't be removed but stated why is not needed. For example, if a mobile app is being build and there is no database, a comment explaining why the Database Schema section has not been written should be left.
• Approval process:
  1. The document must be reviewed by a TL who is fluent on the type of system to be designed (ie. blockchain, smart contracts, distributed systems, micro services). This person must sign of the document before considering it approved and ready to be shared externally.
  2. Optionally could be read by another technical leader in order to spread knowledge amongst Technical Leadership Team.
  3. It must be reviewed and approved by the customer technical authority.
• All the team members should read it and understand it.

Atix - Request for Comments¶

• This document should be written when a new change is going to be introduced into the project original design, any tooling or process already being used in Atix. It might not be written for small or trivial changes.
• The main goal is to explain others and get feedback before making a decision.
• It must be written such that any developer will be able to extract tasks and fully implement the proposed solution.
• Every section should be written based on the guidelines written on the template. Sections that don't apply shouldn't be removed but stated why is not needed. For example, if a mobile app is being build and there is no database, a comment explaining why the Database Schema section has not been written should be left.
• Approval process:
  • If it's a project change, it must be reviewed following the technical specs approval process
  • If it's an internal change (for example to Awesome atix) an RFC must be written and approved by the Principal Tech Lead.

Repository¶

There are a set of file every repository must have:

• README.md: explains how to setup, build and test the project
• CONTRIBUTING.md: a guide about how to start sending merge request to the repo
• LICENSE.md (optional)
• Gitlab's Merge Requests and Issues Description Templates contains the templates to be used in our repository management tool with predefined sections.

Sample documents to be used as reference alongside with instructions can be found here.

It's mandatory to include this files on every Atix repository.